feat(v1.10.0): "Name to fit in" naming convention (detect-and-conform)#6
Merged
Conversation
Adds an explicit naming convention closing two recurring AI failure modes: - casing drift (model imposes its language-default snake_case/camelCase instead of detecting and conforming to the repo's actual style, per kind and per local module) - wrong granularity (names too vague like get() or too verbose/leaking like getting_data_from_mobile()) Deliberately detect-and-conform, NOT a prescribed house style — a house style would contradict the stack's "fit in" north star and be wrong in most client repos. Rationale in new ADR 0010. Touchpoints: - AGENTS.md "Write less, fit in" — tight "Name to fit in" bullet (kept under the 8 KiB lean budget per ADR 0009) - templates/AGENTS.md.example — same bullet, self-contained (shipped artifact) - docs/conventions.md — new "## Naming" section with detection mechanics + granularity guidance - docs/adr/0010-*.md + index entry - CHANGELOG [1.10.0]; version bump 1.9.0 -> 1.10.0 (plugin.json + marketplace.json). Context-map rebuilt. 132 tests pass.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds an explicit naming convention to the stack — the gap Filip flagged: the repo guided code shape (
Write less, fit in) but said almost nothing about how identifiers should be named, beyond one implicit clause. Naming is one of the highest-signal long-term-maintainability factors, and AI agents have two repeatable failure modes here.What it closes
snake_case, JS →camelCase) and silently imposes it on a client repo that deviates, so new code reads as "the AI-written part."get(),data()) or implementation-leaking and verbose (getting_data_from_mobile()).Design: detect-and-conform, not a house style
Casing/separator is treated as repo-specific — the agent must detect the existing convention (per kind, per local module) and conform, never impose its default. Granularity/clarity is a universal quality principle. A prescribed house style was explicitly rejected: it would contradict the "fit in" north star and be wrong in most client repos. Full rationale + rejected alternative in ADR 0010.
Touchpoints
AGENTS.mdName to fit inbullet in "Write less, fit in" (kept under the 8 KiB lean budget)templates/AGENTS.md.exampledocs/conventions.md## Namingsection — detection mechanics + granularity guidancedocs/adr/0010-*.md+ indexCHANGELOG.md[1.10.0]Added entryplugin.json/marketplace.jsonChecks
pytest tests/— 132 passed, 0 failed